diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 9802f831..a546ecc8 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -42,64 +42,29 @@ libraries that Node.js requires. ### Manually -Builds for Linux is released on GitHub: -https://github.com/MatrixAI/Polykey-CLI/releases. - -Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it -to `polykey`. - -Make it executable: - -```sh -$ chmod u+x ./polykey -``` - -### Add it to your `$PATH`. - -#### For ZSH: - -1. `cd` into directory where polykey exec is stored. -2. Edit the zsh config to add polykey to your path. To streamline the process, - run the following command, making sure to change the path to polykey if the - polykey executable is not in the downloads folder. -3. For most users, this would be `~/Downloads` - -:::warning - -Make sure your path to the polykey executable is correct. +#### Using the Polykey CLI via the terminal -::: - -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc -``` - -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. - ---- +If you prefer not to use a package manager or Docker, you can install Polykey directly via the terminal using a prebuilt binary. -#### For Bash: +1. Download the executable from the [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases) and rename it to `polykey`. -1. `cd` into directory where polykey exec is stored. -2. Edit the zsh config to add polykey to your path. To streamline the process, - run the following command, making sure to change the path to polykey if the - polykey executable is not in the downloads folder. -3. For most users, this would be `~/Downloads` +2. Make it executable: -:::warning + ```sh + chmod u+x ./polykey -Make sure your path to the polykey executable is correct. +3. Move it into a directory in your $PATH, or add the current directory to your $PATH temporarily: +* For ZSH: -::: + echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc -``` +* For Bash: + echo 'export PATH=~/Downloads:$PATH' >> ~/.bashrc && source ~/.bashrc -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. +4. Confirm the installation: + polykey --version +If it returns the version, you’re ready to use the CLI. --- ### NixOS diff --git a/docs/README.md b/docs/README.md index fc2fda84..610391f5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,103 +1,107 @@ ---- -slug: / -displayed_sidebar: docs ---- +# **Welcome to the Polykey documentation** -# Polykey Documentation +- [Tutorials:](https://polykey.com/docs/tutorials) Step-by-step guides that + introduce Polykey through practical outcomes. -Welcome to the Polykey documentation. +- [How-To Guides:](https://polykey.com/docs/how-to-guides) Short, targeted + instructions for achieving specific use-cases, assuming prior familiarity. -- [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 +- [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 Gestalt Identity: -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, 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