diff --git a/docs/tutorials/polykey-cli/bootstrapping.md b/docs/tutorials/polykey-cli/bootstrapping.md index d647ceb..a9352a1 100644 --- a/docs/tutorials/polykey-cli/bootstrapping.md +++ b/docs/tutorials/polykey-cli/bootstrapping.md @@ -1,2 +1,127 @@ -# Bootstrap Keypair +# Bootstrapping +## Introduction + +Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. + +## Setting Up Your Node + +### Creating the Root Key + +When you first start the Polykey agent, it automatically generates a random root key. + +This root key is an asymmetric key pair consisting of a public key representing your identity and used for verifying signatures, and a private key which is used for signing. + +Afterwards, encryption keys are derived from this root key, which is used for encryption and decryption of all node state and secret data managed by Polykey. + +You will be prompted to provide a root password. This password encrypts the root key. + +:::note +Remember to keep your password in a secure location as you will need it each time you start the Polykey agent. +::: + +### Starting the Polykey Agent + +You can start the Polykey agent in the foreground of your terminal by running: + +```bash +polykey agent start --verbose +``` + +Running the agent in the foreground allows you to monitor its output directly in the terminal. Ensure this terminal session remains active to keep the agent running. You can execute Polykey commands from any other terminal session while this runs. + +### Starting Polykey in the Background + +Alternatively, in the demo video and other scenarios where you do not wish to occupy your terminal, you can start the agent in the background: + +```bash +polykey agent start --verbose --background +``` + +### Stopping the Polykey Agent + +You can stop the Polykey agent by pressing **Control+C** in the terminal where it's running in the foreground, or by running: + +```bash +polykey agent stop +``` + +#### Troubleshooting + +If the Polykey agent does not terminate properly, you can force quit the process through the Activity Monitor on your machine. If you encounter this or any other issue, please consider making a [bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help improve Polykey. + +## Check Agent Status + +To check the status of your Polykey node, use the following command: + +```bash +polykey agent status +``` + +This command provides detailed information about your node's current state, including its connectivity and activity within the network. + +### Example Output + +```bash +status LIVE +pid 96992 +nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +clientHost ::1 +clientPort 54975 +agentHost :: +agentPort 60358 +upTime 8 +startTime 1716509093 +connectionsActive 3 +nodesTotal 11 +version 1.2.3-alpha.4-1-1 +sourceVersion 1.2.3-alpha.4 +stateVersion 1 +networkVersion 1 +``` + +## Check Network Status + +When your agent has started, it should show as a node on the network. By default the network is [mainnet](https://mainnet.polykey.com/). Check out the network dashboard to see your placement on the world map. + +## Monitoring Network Connections + +To view the nodes currently connected to the network, including the seed nodes, run: + +```bash +polykey nodes connections +``` + +This will list all active connections, including details about each node. + +### Example Output + +```bash +host hostname nodeIdEncoded port timeout usageCount +3.145.86.40 N/A v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 1314 46873 0 +13.239.117.143 N/A vncm2mkk41vgp2fmplqiu1je7b2l3v6fhgltlqf5f3f85923ve0j0 1314 116186 0 +1.145.55.96 N/A vg6gldhfdstju8frtbguav2p2svmev85dvpdb34gffmiagpgjf2pg 1200 102086 0 +``` + +## Checking Node Activity + +To determine if a specific node is active, use the ping command: + +```bash +polykey nodes ping +``` + +This will tell you whether the node is active within the network. + +### Example Output + +```bash +polykey nodes ping v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 +Node is Active +``` + +## Conclusion + +Bootstrapping your node is the first step to using Polykey effectively. It prepares your node for managing and sharing secrets securely within the network. By following these guidelines, you ensure that your node is well-configured, secure, and ready for advanced operations in the Polykey ecosystem. + +Stay tuned for upcoming sections where we will discuss managing multiple nodes, assigning different file paths to each node, and other advanced configurations. diff --git a/docs/tutorials/polykey-cli/managing-secrets.md b/docs/tutorials/polykey-cli/managing-secrets.md index c869d81..9b227d7 100644 --- a/docs/tutorials/polykey-cli/managing-secrets.md +++ b/docs/tutorials/polykey-cli/managing-secrets.md @@ -1 +1,368 @@ # Managing Secrets + +## Introduction + +Secrets in Polykey are essential for securely managing sensitive information, such as API keys, configuration files, or documents. These can be any file type that you need to encrypt and manage securely. This section provides a detailed guide on how to manage these secrets within vaults using Polykey-CLI. + +:::tip + +In the Polykey CLI, you can get help with managing your Secrets Operations by using the `-h` help command to get a detailed list of availiable options and commands. Try running `polykey secrets -h` +::: + +## Creating Secrets + +:::note + +**Create a Secret within a given Vault** + +**Usage:** `polykey secrets create [options] ` + +**Arguments:** + +**directoryPath:** On disk path to the secret file with the contents of +the new secret. + +**secretPath:** Path to the secret to be created, + +specified as `:` +::: + +### Adding a Secret to a Vault + +The `polykey secrets create` command clones an existing file from your local machine and stores it into an encrypted vault, creating a secret in the process. Thus, providing secure data-at-rest encryption of the file. + +:::tip +To create a secret, both the vault and file you are creating a secret from, must already exist. Remember that to view the vaults contained within a node, you run `$polykey vaults list`. This is useful for viewing the names of the vaults you are trying to manage secrets with, as vaultName is one of the command arguments that is commonly used. +::: + +#### Command Arguments + +```bash +polykey secrets create : +``` + + + +:::info +The `` for the file you are trying to create a secret from can either be a working directory filepath or a root path. Also notice that we either have 1 space of seperation or a `:` between command arguments usually. The angle braces are just being used in our explanation for specifying the arguments more clearly. +::: + +#### Example Usage of `Polykey Secrets Create` + +```bash +polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY +``` + +This command cloned the `API_ACCESS_KEY.txt` file from the terminal's working directory and saved it in a vault named `my-api-vault`, specifying the secretName alias as `API_ACCESS_KEY`. We could have also provided the secretName alias as `API.ACCESS_KEY.txt` but for most text files in Polykey, specifying the file type extension is redundant. + +:::tip +Since the secret or `` stored in the vault does not specify the file type in its metadata, when you are storing binary files such as images or videos, you may want to specify the file extension in the `secretName` alias for better access & manageability. +::: + +## Listing Secrets + +:::note +**List all Available Secrets for a Vault** + +**Usage:** `polykey secrets list|ls [options] ` + +**Arguments:** + +**vaultName:** Name of the vault to list secrets from + +::: + +To list the secret file(s) stored within a specific vault in your default nodePath, use: + +#### Command Arguments: + +```bash +polykey secrets list +``` + +#### Example Usage + +```bash +Polykey secrets list my-api-vault +``` + +#### Example Output + +In this case, there's just one secret file contained in this vault, the secret we created in the previous example. + +```bash +API_ACCESS_KEY +``` + +:::note + +### Secure Deletion of Local Secrets + +After adding a secret to a vault, securely delete the local copy if it's no longer needed. This ensures that no unsecured traces of sensitive information remain on your local filesystem. +::: + +## Retreiving Secrets + +Retrieve a secret from the given vault using the polykey secrets get command. This command accesses the encrypted content within a vault and outputs it, allowing for further handling depending on the file type. + +:::note + +Retrieve a Secret from the Given Vault + +**Usage:** `polykey secrets get [options] ` + +**Arguments:** + +**secretPath:** Path to where the secret to be retrieved, + +specified as `:` + +::: + +### Text and Binary File Handling + +The nature of the file affects how it is handled when retrieved: + +- **Text Files:** Files such as .txt, .cfg, or script files like .sh are inherently text-based and can be displayed directly in the terminal. This feature is useful for quick checks and edits directly from the command line. + +- **Binary Files:** Files like images, executables, or other non-text formats are binary files. These do not display readable content directly in the terminal and must be handled differently. + +### Retrieving a Text File + +To view the contents of a text file stored in a vault directly from the terminal, use the following command: + +```bash +polykey secrets get : +``` + +#### Example: Retrieving a Text File + +Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault-tutorial-1` + +```bash +polykey secrets get my-vault-tutorial-1:API_ACCESS_KEY +``` + +#### Example Output + +```bash +AKfjd39jdi3903KDje93j04j0 +``` + +This method displays text files directly in the terminal, providing immediate access to the contents. + +### Retrieving Binary File + +Binary files, such as images or executables, need to be handled appropriately to view or use their contents correctly. + +#### Steps to Retrieve a Binary File + +To retrieve and handle a binary file, specify the output format by redirecting the output to a file with the appropriate file extension: + +```bash +polykey secrets get : > . + +``` + +This command saves the binary content into a file in the current local directory, preserving the file type as indicated by the extension ``. + +#### Example: Retrieving and Viewing an Image + +Retrieve an image stored in a vault and view it using system-specific commands: + +```bash +polykey secrets get my-NFT:Dali.png > Dali.png +open Dali.png +``` + +:::note +The use of `>` in the command line is a standard Unix redirection operator, used here to direct the output from Polykey into a file. This operation is necessary for handling binary files that require specific applications to open. +::: + +:::tip +Ensure the secret name includes the file extension (like Dali.png), which helps clarify the file type when saving and accessing the retrieved file. +::: + +## Creating a Directory of Secrets + +To create a directory within a vault, use the polykey secrets mkdir command. This command allows you to organize your secrets into directories within a vault. + +```bash +polykey secrets mkdir : +``` + +#### Example: Creating a Directory in a Vault + +To create a directory named "NFTs" within the "my-image-vault": + +```bash +polykey secrets mkdir my-image-vault:NFTs +``` + +### Adding a Secret to a Directory in a Vault + +After creating a directory, you can add secrets to it. This helps in organizing similar types of secrets under a common directory. + +```bash +polykey secrets create :/ +``` + +#### Example: Adding a Secret to a Directory + +To add the file "Dali.png" as a secret named "Dali.png" to the "NFTs" directory within "my-image-vault": + +```bash +polykey secrets create ./Dali.png my-image-vault:NFTs/Dali.png +``` + +:::note +To view secrets saved within a directory in a vault, using the `polykey secrets list ` command for that vault will output all secrets in the vault, including those within directories. + +**Example Usage** + +```bash + polykey secrets list my-image-vault +``` + +**Output** + +```bash +NFTs/Owner.png +``` + +::: + +## Renaming a Secret + +To rename an existing secret: + +```bash +polykey secrets rename : +``` + +:::tip +Use the `secrets list` command to check on your renamed secretFile. +::: + +## Updating a Secret + +To update the contents of an existing secret: + +```bash +polykey secrets update : +``` + +#### Example: Secrets Update + +```bash +polykey secrets update ./rare-dali.png my-image-vault:NFTs/Dali.png +``` + +:::info +This is essentially replacing the file content of an existing secret while preserving the identity of the secret. One way to verify that the update was performed sucesfully is by viewing the mtime (modified time) timestamp from the `secrets stat` command. +::: + +## Retrieving Secret Metadata + +To view metadata about a secret: + +```bash +polykey secrets stat : +``` + +#### Example: Viewing Metadata for a Secret + +```bash +polykey secrets stat my-image-vault:NFTs/Dali.png +``` + +#### Example Output + +```yaml +dev 0 +ino 158 +mode 33188 +nlink 1 +uid 0 +gid 0 +rdev 0 +size 23450 +atime Sat May 25 2024 17:22:34 GMT-0600 +mtime Sat May 25 2024 17:22:33 GMT-0600 +ctime Sat May 25 2024 17:22:33 GMT-0600 +birthtime Fri May 24 2024 22:42:43 GMT-0600 +blksize 4096 +blocks 6 +``` + +:::note + +### Understanding Metadata Terms + +- **dev:** Device number on which the file resides. +- **ino:** File's inode number. +- **mode:** File permission and type encoded in numeric format. +- **nlink:** Number of hard links. +- **uid:** User ID of file's owner. +- **gid:** Group ID of file's owner. +- **rdev:** Device ID (if special file). +- **size:** File size in bytes. +- **atime:** Last access timestamp. +- **mtime:** Last modification timestamp. +- **ctime:** Last status change timestamp. +- **birthtime:** Creation time of the file. +- **blksize:** Block size for filesystem I/O. +- **blocks:** Number of 512-byte blocks allocated. + +::: + +## Deleting Secrets + +To remove a secret from a vault: + +```bash +polykey secrets delete : +``` + +#### Example: Deleting a Secret + +```bash +polykey secrets list my-image-vault +``` + +**Output:** + +```bash +NFTs/Dali.png +THE_THIEF.png +``` + +```bash +polykey secrets delete my-image-vault:THE_THIEF.png +``` + +Successful deletion does not produce output. Verify the secret was removed by listing secrets in the vault. + +```bash +polykey secrets list my-image vault +``` + +**Output:** + +Notice that we have sucesfully removed one of the secrets from the vault now. + +```bash +NFTs/Dali.png +``` + +## Editing Secrets in a Vault + +To edit a secret directly within a Vault using Polykey: + +```bash +polykey secrets edit : +``` + +:::warning +Polykey Secrets Edit on Mac OS has a bug that we are investigating. Use Polykey Secrets Update in the meantime. +::: diff --git a/docs/tutorials/polykey-cli/managing-vaults.md b/docs/tutorials/polykey-cli/managing-vaults.md index ea42059..d8ee718 100644 --- a/docs/tutorials/polykey-cli/managing-vaults.md +++ b/docs/tutorials/polykey-cli/managing-vaults.md @@ -1 +1,122 @@ # Managing Vaults + +## Introduction + +Vaults in Polykey are secure containers where you can store and manage secrets like passwords, tokens, certificates, and keys. Vaults are encrypted and only accessible within your Polykey node. This section covers the basics of managing vaults, including creating, listing, deleting, viewing vault history, and renaming them. + +## Creating a Vault + +To create a new vault, use the following command: + +```bash +polykey vaults create +``` + +#### Example + +Create a new vault named `myvault`: + +```bash +polykey vaults create myvault +``` + +#### Example Output + +```bash +Vault zUvPxC9aKNw94E1yR9dffzY created successfully +``` + +## Listing Vaults + +To see all the vaults you have, use the list command. This provides a simple way to view all vault names and their identifiers. + +```bash +polykey vaults list +``` + +#### Example Output + +```bash +my-software-project zD8XRJw2SoRoUW5e2mBR9tJ +myvault zD3cWJLBDEMWcbwNbjuUevo +myvault-101 zErezdpLocYs1VRZPV3wcqS +``` + +## Deleting a Vault + +If you need to remove a vault, you can delete it using the delete command: + +```bash +polykey vaults delete +``` + +#### Example + +Delete the vault named myvault: + +```bash +polykey vaults delete myvault +``` + +This operation does not produce output on successful execution, indicating the vault has been removed. + +## Viewing Vault History + +Each vault maintains a version history which tracks changes over time. Use the log command to view the history of commits to a vault. + +```bash +polykey vaults log +``` + +#### Example + +View the log for `my-software-project`: + +```bash +polykey vaults log my-software-project +``` + +#### Example Output + +```bash +commitId b568873376cd74a6c58755f73d1068cbb52cbc84 +committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +timestamp Tue May 14 2024 21:27:52 GMT-0600 (Mountain Daylight Time) +message "AWS_SECRET_ACCESS_KEY added\n" +commitId 4d664db1f90f4c03d6c72be0fba4d3d1a3e7bda0 +committer vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg +timestamp Tue May 14 2024 21:27:43 GMT-0600 (Mountain Daylight Time) +message "AWS_ACCESS_KEY_ID added\n" +``` + +## Renaming a Vault + +To change the name of an existing vault, use the rename command. This allows you to update the vault's name to something more descriptive or appropriate. + +```bash +polykey vaults rename +``` + +#### Example + +Rename `myvault-1` to `myvault-101`: + +```bash +polykey vaults rename myvault-1 myvault-101 +``` + +Confirm the rename by running: + +```bash +polykey vaults list +``` + +## Conclusion + +Managing vaults is a foundational skill in using Polykey effectively. This section has guided you through the essential commands needed to create, manage, and organize your vaults within Polykey. Further capabilities such as setting permissions, sharing vaults, and pulling vaults from other nodes will be covered in the Secrets Management section of our documentation. These basic functionalities ensure that your secrets are well-organized and secure within the network. + +For a full list of vault commands and options, run: + +```bash +polykey vaults -h +```