diff --git a/docs/README.md b/docs/README.md index fc2fda84..830473ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,101 +3,110 @@ slug: / displayed_sidebar: docs --- -# Polykey Documentation +# **Welcome to the Polykey documentation** -Welcome to the Polykey documentation. +- [Tutorials:](https://polykey.com/docs/tutorials) Step-by-step guides that + introduce Polykey through practical outcomes. -- [Tutorials](./tutorials) - these are a series of steps to introduce Polykey to - new beginners to achieve a practical outcome -- [How-To Guides](/docs/how-to-guides) - these are short guides on how to - achieve a specific use-case which makes assumptions on the reader -- [Theory](./theory/) - these are important for understanding the "why" of - Polykey -- [Reference](./reference/) - these are useful when you need remember how to use - a particular command or function +- [How-To Guides:](https://polykey.com/docs/how-to-guides) Short, targeted + instructions for achieving specific use-cases, assuming prior familiarity. + +- [Theory:](https://polykey.com/docs/theory/) Conceptual foundations explaining + the rationale behind Polykey. + +- [Reference:](https://polykey.com/docs/reference/) Lookup documentation for + commands, functions, and technical specifications. ## Introduction -Polykey helps yourself, teams and software agents to manage and share secrets in -a secure and easy-to-use manner. - -- Usable for the average person, you don't need to be a cryptography or - cybersecurity expert to securely manage and share secrets. -- Can be integrated into software for automation of secret workflows. -- Unifies the workflow between interactive password management and - infrastructure key management. -- Decentralized and local-first software that does not hand over your secrets to - the cloud. You maintain sovereignty over your secrets on your devices. -- Easily backup and synchronise your secrets across all your devices: desktop, - mobile or server. -- End to end encryption for all network communication. -- All data is encrypted at rest, thus preventing compromise even if devices are - lost or stolen. - -PolyKey is an open-source decentralised peer to peer secrets management system. -It provides a software agent that runs on your device locally. Each agent -process is a node in the Polykey peer to peer network. This agent manages your -secret data and is capable of sharing secrets with other trusted Polykey agents. -The secret data can be placed inside any directory on your computer including on -USB storage. +Polykey helps individuals, teams, and software agents manage and share secrets +securely and intuitively. + +- **User-Friendly:** Designed for everyday users, with no need to be a + cryptography or cybersecurity expert. + +- **Automation-Ready:** Integrates into software workflows for automated secret + handling. + +- **Unified Secrets Management:** Bridges the gap between personal password + management and infrastructure-level key handling. + +- **Decentralized and Local-First:** Your secrets never leave your device unless + you choose to share them. + +- **Seamless Synchronization:** Backup and sync secrets across desktops, mobile + devices, and servers. + +- **Comprehensive Encryption:** All data is end-to-end encrypted in transit and + encrypted at rest. + +Polykey is an open-source, peer-to-peer secrets management system. Each Polykey +agent runs locally as a node in the network, managing secrets and enabling +sharing with trusted peers. Secrets are stored within encrypted vaults and can +be placed anywhere on your system, including external storage like USB drives. ## Features -TBD +Polykey delivers robust, decentralized secrets management through the following +capabilities: -## Principles +- **Decentralized & Local-First:** Operates entirely on your device in a + peer-to-peer network, giving you full control over your secrets. -There are 2 main concepts to understand in Polykey: +- **State-of-the-Art Cryptography:** Employs XChaCha20-Poly1305 for encryption, + X25519 for key exchange, and Ed25519 for signatures, ensuring confidentiality + and integrity. -- Secrets Management -- Decentralized Trust +- **Secure Vault Architecture:** Secrets are organized into fully encrypted, + version-controlled vaults that function like a secure, virtual filesystem, + enabling safe storage, backup, and sharing with trusted peers. Data remains + encrypted at rest, even when the Polykey agent is not running. It is only + decrypted when the agent is launched and the user authenticates. -### Secrets Management +- **Gestalt Identity Model:** Aggregates multiple digital identities into a + unified, trusted representation to facilitate secure sharing. -Polykey was built from the ground up to focus on secrets management. +- **Integration & Automation:** Works interactively or via CLI integration for + seamless inclusion in CI/CD pipelines and system workflows. -Secrets can be any kind of data that enables some sort of capability in the -physical or virtual world. +- **Cross-Platform & Open Source:** Actively maintained, open-source, and + operable across multiple environments. -The world is full of secrets. For example, a password is a secret that enables -you to login to a website. A private key is a secret that enables you to sign -and verify some data. A symmetric key is a secret that enables you to encrypt -and decrypt some data. A token is a secret that enables software agents and -machines to authenticate to remote services. A credit card is a secret that -enables payments. +- **Forward-Looking Security:** Investigating post-quantum cryptography and + advanced protective mechanisms to stay ahead of evolving threats. -Polykey is designed to manage all kinds of secrets. It is not limited to -passwords or keys. +## Core Concepts -For this reason, we think of secrets as "capabilities". +### Secrets Management -All secrets are put into vaults. Each vault is a persistent, fully encrypted -virtual filesystem with automatic version history. Vaults can be shared with -other Polykey agents. +Polykey was purpose-built for secrets management: any data that enables +capability. -Polykey's secrets management system provides users with secure communication and -secure computation. +- **Passwords** for authentication -### Decentralized Trust +- **Private Keys** for signing or decryption -Sharing secrets depends on secure communications. Secure communications depends -on trusted identities. +- **Tokens** for machine-to-service authentication -Polykey introduces a concept called "Gestalt Identity". +- **Credit Card Info** for payments + +All secrets are stored in encrypted vaults with automatic versioning. Vaults can +be shared securely with other Polykey agents. Secrets are treated as +capabilities, or elements that grant power in both digital and physical systems. + +### Decentralized Trust -A Gestalt Identity is a collection of digital identities (i.e. social media -profiles and Polykey nodes) that all represent the same entity. +Secret sharing relies on secure communications, which require trusted +identities. Polykey introduces this via the concept of a Gestalt. -When you start a Polykey agent, it immediately forms its own gestalt with the -Polykey node as its only identity. Link up your digital identities to the node -in order to expand your gestalt. +A **Gestalt Identity** is a collection of digital identities (e.g. social +profiles or Polykey nodes) representing the same person or agent. -As you deploy more Polykey agents, you can join existing gestalts. +- When a Polykey agent starts, it begins with a single-node gestalt. -Your gestalt is how other users are able to share secrets with a trusted -identity. Your identity is the sum of the reputation of all your digital -identities that are part of the gestalt. +- Users can link other identities to expand trust. -## Comparison to other Tools +- Gestalts allow others to verify and trust your identity when sharing secrets. -TBD +Trust in Polykey is compositional, built from the integrity of all linked +identities in your gestalt. diff --git a/docs/reference/architecture/encryption-algorithms.md b/docs/reference/architecture/encryption-algorithms.md index 131e49e3..bbfda907 100644 --- a/docs/reference/architecture/encryption-algorithms.md +++ b/docs/reference/architecture/encryption-algorithms.md @@ -14,12 +14,21 @@ 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. +-### Symmetric Encryption + +- **XChaCha20-Poly1305 (IETF)** + - **Key Size:** 256 bits + - **Nonce Size:** 192 bits + - **MAC Size:** 128 bits + - This extended 192-bit nonce allows random nonces to be safely used, reducing + the risk of nonce reuse and making the encryption scheme misuse-resistant. + - A stream cipher approach is employed, encrypting data per block with a + fresh, random nonce each time. + - Polykey stores its persistent state in an encrypted database, protected by a + “Data Encryption Key” (DEK). This DEK is not derived from the root key, so + rotating the root key does not require re-encrypting the entire database. + - By combining encryption and authentication, XChaCha20-Poly1305 ensures both + confidentiality and integrity of the stored data. ### Asymmetric Encryption