From bea2de8c84bc39adf05117660d69368bf879eff9 Mon Sep 17 00:00:00 2001 From: Awiteb Date: Tue, 14 May 2024 11:20:48 +0300 Subject: [PATCH] feat: Initialize Lprs book --- docs/SUMMARY.md | 15 ++++ docs/commands/README.md | 46 ++++++++++ docs/commands/add.md | 92 ++++++++++++++++++++ docs/commands/auto-completion.md | 25 ++++++ docs/commands/change-master-password.md | 3 + docs/commands/clean.md | 19 ++++ docs/commands/edit.md | 85 ++++++++++++++++++ docs/commands/gen.md | 38 ++++++++ docs/commands/get.md | 57 ++++++++++++ docs/commands/import-export.md | 111 ++++++++++++++++++++++++ docs/commands/list.md | 24 +++++ docs/commands/remove.md | 42 +++++++++ docs/installation.md | 13 +++ docs/introduction.md | 58 +++++++++++++ 14 files changed, 628 insertions(+) create mode 100644 docs/SUMMARY.md create mode 100644 docs/commands/README.md create mode 100644 docs/commands/add.md create mode 100644 docs/commands/auto-completion.md create mode 100644 docs/commands/change-master-password.md create mode 100644 docs/commands/clean.md create mode 100644 docs/commands/edit.md create mode 100644 docs/commands/gen.md create mode 100644 docs/commands/get.md create mode 100644 docs/commands/import-export.md create mode 100644 docs/commands/list.md create mode 100644 docs/commands/remove.md create mode 100644 docs/installation.md create mode 100644 docs/introduction.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..7b92d3e --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,15 @@ +# Lprs Documentation + +- [Introduction](introduction.md) +- [Installation](installation.md) +- [Command line usage](commands/README.md) + - [Adding a vault](commands/add.md) + - [Removing a vault](commands/remove.md) + - [Editing a vault](commands/edit.md) + - [Getting a vault](commands/get.md) + - [Listing all vaults](commands/list.md) + - [Clening the vaults](commands/clean.md) + - [Generating a password](commands/gen.md) + - [Importing and exporting vaults](commands/import-export.md) + - [Changing the master password](commands/change-master-password.md) + - [Auto completion](commands/auto-completion.md) diff --git a/docs/commands/README.md b/docs/commands/README.md new file mode 100644 index 0000000..4a6af93 --- /dev/null +++ b/docs/commands/README.md @@ -0,0 +1,46 @@ +# Command line usage + +This section provides a reference for the various commands and options that are +available in the `lprs` command line tool, and how to use them. + +But before we dive into the commands, let's take a look at the `lprs` main +options, which are available for all commands. + +``` +Options: + -f, --vaults-file The vaults json file + -v, --verbose Show the logs in the stdout + -m, --master-password The master password, or you will prompt it + -h, --help Print help + -V, --version Print version +``` + +As you can see, the `lprs` command line tool has a few options that are +available for all commands, which are: + +- `-f, --vaults-file `: The vaults json file, this is the file + where the vaults are stored. By default, the vaults are stored in the + program's directory, in a directory called `lprs` and the file called + `vaults.lprs`. +- `-v, --verbose`: Show the logs in the stdout, this option is useful for + debugging purposes. +- `-m, --master-password `: The master password, this is the + password that is used to encrypt and decrypt the vaults, usful for scripting + purposes, otherwise you will be prompted for the master password (which is + better for security reasons) + +Now let's take a look at the available commands and how to use them. + +- [Adding a vault](commands/add.md) +- [Removing a vault](commands/remove.md) +- [Editing a vault](commands/edit.md) +- [Getting a vault](commands/get.md) +- [Listing all vaults](commands/list.md) +- [Clening the vaults](commands/clean.md) +- [Generating a password](commands/generate-password.md) +- [Importing and exporting vaults](commands/import-export.md) +- [Changing the master password](commands/change-master-password.md) +- [Auto completion](commands/auto-completion.md) + +## Donations +You can support the development of my projects by donating me, check out my profile at [git.4rs.nl](https://git.4rs.nl/awiteb#donations) diff --git a/docs/commands/add.md b/docs/commands/add.md new file mode 100644 index 0000000..c9617de --- /dev/null +++ b/docs/commands/add.md @@ -0,0 +1,92 @@ +# Adding a vault + +## Usage + +``` +Usage: lprs add [OPTIONS] + +Arguments: + + The name of the vault + +Options: + -u, --username + The username + + -s, --service + The service name. e.g the website url + + -n, --note + Add a note to the vault + + --totp-hash + The TOTP hash function + + [default: sha1] + + Possible values: + - sha1: Sha1 hash function + - sha256: Sha256 hash function + - sha512: Sha512 hash function + + -p, --password [] + The password, if there is no value you will prompt it + + -t, --totp-secret [] + The TOTP secret, if there is no value you will prompt it + + -c, --custom + Add a custom field to the vault + + -f, --force + Force add, will not return error if there is a problem with the args. + + For example, duplication in the custom fields and try to adding empty vault + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +So, to add a vault you need to provide a name for the vault, and you can provide +a username, service name, note, password, TOTP secret, and custom fields. + +For secrets like the password and TOTP secret, you can provide them as arguments +or you will be prompted for them. + +### Custom fields +You can't add a custom field prefixed with `.lprsfield.` because it's reserved +for backwards compatibility. + +## Examples +Add a vault: +```sh +lprs add my-vault1 -u my-username -s my-service -n 'My super secret note' \ + -p my-password -t 'JFWG65TFKJ2XG5BO' \ + -c key1=value1 -c key2=value2 +``` + +Add a vault with a username and a password, but prompt for the password: +```sh +# -p without a value will prompt you for the password +lprs add my-vault2 -u my-username -p +``` + +Add a vault with a username, a password, and custom fields: +```sh +# The password will be prompted +lprs add my-vault3 -u my-username -p \ + -c key1=value1 \ + -c 'long key'='long value' +``` + +## Notes +- You must provide a name for the vault and at least one of the following: + username, password, TOTP secret, or custom fields. +- If you provide a password or TOTP secret as an argument, it will be visible in + the shell history. +- You can use existing vault names, and it will not be overwritten, so if you + edit, get, or remove a vault by its name, it will be the first one found, so + be careful with the names. diff --git a/docs/commands/auto-completion.md b/docs/commands/auto-completion.md new file mode 100644 index 0000000..74828a8 --- /dev/null +++ b/docs/commands/auto-completion.md @@ -0,0 +1,25 @@ +# Auto completion + +## Usage + +``` +Usage: lprs completion + +Arguments: + Shell to generate completion for [possible values: bash, elvish, fish, powershell, zsh] + +Options: + -h, --help Print help +``` + +The `completion` command generates completion scripts for the specified shell. The output is written to `stdout`, so you can redirect it to a file and source it in your shell configuration file. + +## How to use + +| Shell | Command to generate completion script | Command location (the file to write the command in) | +|------------|---------------------------------------|----------------------------------------------------| +| Bash | `eval "$(lprs completion bash)"` | `~/.bashrc` | +| Elvish | `eval (lprs completion elvish \| slurp)` | `~/.elvish/rc.elv` | +| Fish | `lprs completion fish \| source` | `~/.config/fish/config.fish` | +| Powershell | `Invoke-Expression (& { (lprs completion powershell \| Out-String) })` | run `echo $PROFILE` | +| Zsh | `eval "$(lprs completion zsh)"` | `~/.zshrc` | diff --git a/docs/commands/change-master-password.md b/docs/commands/change-master-password.md new file mode 100644 index 0000000..1575e9f --- /dev/null +++ b/docs/commands/change-master-password.md @@ -0,0 +1,3 @@ +# Changing the master password + +## Usage diff --git a/docs/commands/clean.md b/docs/commands/clean.md new file mode 100644 index 0000000..75a29c0 --- /dev/null +++ b/docs/commands/clean.md @@ -0,0 +1,19 @@ +# Clening the vaults + +## Usage + +``` +Usage: lprs clean + +Options: + -h, --help Print help + -V, --version Print version +``` + +Is simple, just run `lprs clean` and the vaults file will be cleaned, removing +all the vaults from it. + +## Notes +- You can't undo this action, so be careful when using it. +- You can specify the vaults file by using the `--vaults-file` option. [See main + lprs options](./index.html). diff --git a/docs/commands/edit.md b/docs/commands/edit.md new file mode 100644 index 0000000..c1ed248 --- /dev/null +++ b/docs/commands/edit.md @@ -0,0 +1,85 @@ +# Editing a vault + +## Usage + +``` +Usage: lprs edit [OPTIONS] + +Arguments: + + The vault to edit, index or name + +Options: + -n, --name + The new vault name + + -u, --username + The new vault username + + -p, --password [] + The new password, if there is no value for it you will prompt it + + -s, --service + The new vault service + + -o, --note + The new vault note + + -t, --totp-secret [] + The TOTP secret, if there is no value you will prompt it + + -c, --custom + The custom field, make its value empty to delete it + + If the custom field not exist will created it, if it's will update it + + -f, --force + Force edit, will not return error if there is a problem with the args. + + For example, duplication in the custom fields and try to editing nothing + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +To edit a vault you need to provide the index or the name of the vault. If you +provide the index, the vault will be edited by its index, if you provide the +name, the vault will be edited the first vault with the given name. + +You can edit the vault name, username, password, service, note, TOTP secret, and +custom fields. + +For secrets like the password and TOTP secret, you can provide them as arguments +or you will be prompted for them. + +## Custom fields +If you want to add a custom field to the vault, you can use the `-c, --custom` +option, and provide the key-value pair. If you want to delete a custom field, +you can provide the key with an empty value, e.g. `-c key=""`. If the custom +field not exist it will be created, if it's exist it will be updated. + +You can't add a new custom field prefixed with `.lprsfield.` because it's +reserved for backwards compatibility. + +## Examples +Edit a vault by its index: +```sh +lprs edit 1 -n new-vault-name -u new-username -p new-password -s new-service -o new-note -t new-totp-secret -c key1=value1 -c key2=value2 +``` + +Edit a vault password by its name: +```sh +# You will be prompted for the new password +lprs edit my-vault -p +``` + +Remove a custom field from a vault by its name: +```sh +lprs edit my-vault -c key1="" +``` + +## Notes +- The index is one-based (the first vault is 1). diff --git a/docs/commands/gen.md b/docs/commands/gen.md new file mode 100644 index 0000000..6fad352 --- /dev/null +++ b/docs/commands/gen.md @@ -0,0 +1,38 @@ +# Generating a password + +## Usage + +``` +Usage: lprs get [FIELD] + +Arguments: + [LENGTH] The password length [default: 18] + +Options: + -u, --uppercase With uppercase letters (A-Z) + -l, --lowercase With lowercase letters (a-z) + -n, --numbers With numbers (0-9) + -s, --symbols With symbols (!,# ...) + -h, --help Print help + -V, --version Print version +``` + +Generate a password with the specified length, by default the length is `18`, +you can specify the length by passing the `LENGTH` argument. + +This command is useful when you need to generate a password for a new vault. + +## Examples +Generate a password of length 20 with uppercase letters, lowercase letters, +numbers, and symbols: +```sh +lprs gen 20 -ulns +``` + +Generate a password of length 20 for a new vault: +```sh +lprs add my-vault -u 'username' -p $(lprs gen 20 -ulns) +``` + +## Notes +- You must specify at least one of the options to generate a password. diff --git a/docs/commands/get.md b/docs/commands/get.md new file mode 100644 index 0000000..e4f901e --- /dev/null +++ b/docs/commands/get.md @@ -0,0 +1,57 @@ +# Getting a vault + +## Usage + +``` +Usage: lprs get [FIELD] + +Arguments: + + Whether the index of the vault or its name + + [FIELD] + A Specific field to get. + + Can be [name, username, password, service, note, totp_secret, totp_code, "string"] + + where the string means a custom field + +Options: + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +Get a single field from a vault, if the field is not provided, the whole vault +will be printed. If the field is a custom field, you need to provide it as a +string. + +Also, if the vault you specified does not contained the field you provided, an +error will be returned. + + +### Examples +Get the whole vault by its index: +```sh +lprs get 1 +``` + +Get the whole vault by its name: +```sh +lprs get my-vault +``` + +Get a specific field from a vault by its name: +```sh +lprs get my-vault password +``` + +Get a custom field from a vault by its name: +```sh +lprs get matrix_home_server "host" +``` + +## Notes +- The index is one-based (the first vault is 1). diff --git a/docs/commands/import-export.md b/docs/commands/import-export.md new file mode 100644 index 0000000..42eb78b --- /dev/null +++ b/docs/commands/import-export.md @@ -0,0 +1,111 @@ +# Importing and exporting vaults + +## Import usage + +``` +Usage: lprs import [OPTIONS] + +Arguments: + + The file path to import from + +Options: + -f, --format + The format to import from + + [default: lprs] + + Possible values: + - lprs: The lprs format, which is the default format and is is the result of the serialization/deserialization of the Vaults struct + - bit-warden: The BitWarden format, which is the result of the serialization/deserialization of the BitWardenPasswords struct + + -p, --decryption-password [] + Decryption password of the imported vaults (in `lprs` format) if there is not, will use the master password + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +## Export usage + +``` +Usage: lprs export [OPTIONS] + +Arguments: + + The path to export to + +Options: + -f, --format + Format to export vaults in + + [default: lprs] + + Possible values: + - lprs: The lprs format, which is the default format and is is the result of the serialization/deserialization of the Vaults struct + - bit-warden: The BitWarden format, which is the result of the serialization/deserialization of the BitWardenPasswords struct + + -p, --encryption-password [] + Encryption password of the exported vaults (in `lprs` format) if there is not, will use the master password + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version +``` + +To import and export vaults you need to provide the path to the file to import +from or export to, and you can provide the format to import from or export to, +the format can be `lprs` or `bit-warden`, and the imported or exported file must +be `.json` file. + +For the import command, you can provide the decryption password of the imported +vaults if they are exported in the `lprs` format, if there is no decryption +password provided, the master password will be used. + +For the export command, you can provide the encryption password of the exported +vaults in the `lprs` format, if there is no encryption password provided, the +master password will be used. + +## Examples +Import vaults from a file in the `lprs` format: +```sh +lprs import /path/to/vaults.json +``` + +Import vaults from a file in the `lprs` format with a decryption password (You +will be prompted for the decryption password): +```sh +lprs import /path/to/vaults.json -p +``` + +Import vaults from a file in the `bit-warden` format: +```sh +lprs import /path/to/vaults.json -f bit-warden +``` + +Export vaults to a file in the `lprs` format (is the default format): +```sh +lprs export /path/to/vaults.json +``` + +export vaults to a file in the `lprs` format with an encryption password (You +will be prompted for the encryption password): +```sh +lprs export /path/to/vaults.json -p +``` + +Export vaults to a file in the `bit-warden` format: +```sh +lprs export /path/to/vaults.json -f bit-warden +``` + +## Notes +- The imported or exported file must be a `.json` file. +- The imported vaults will be added to the current vaults. +- The imported vaults must don't have a custom field prefixed with `.lprsfield.` + because it's reserved for backwards compatibility. diff --git a/docs/commands/list.md b/docs/commands/list.md new file mode 100644 index 0000000..367c1bf --- /dev/null +++ b/docs/commands/list.md @@ -0,0 +1,24 @@ +# Listing all vaults + +## Usage + +``` +Usage: lprs list [OPTIONS] + +Options: + -f, --filter Filter the select list + -r, --regex Enable regex when use `--filter` option + --json Returns the output as `json` list of vaults + -h, --help Print help + -V, --version Print version +``` + +Lprs `list` command is used to list all vaults in the vaults file, you can also +filter the list by using the `--filter` option, and you can enable regex by +using the `--regex` flag. Also you can get the output as `json` by using the +`--json` flag (this is useful when you want to use the output in a script and +work with it with `jq`). + + +### Examples + diff --git a/docs/commands/remove.md b/docs/commands/remove.md new file mode 100644 index 0000000..ce4bdfd --- /dev/null +++ b/docs/commands/remove.md @@ -0,0 +1,42 @@ +# Removing a vault + +## Usage + +``` +Usage: lprs remove [OPTIONS] + +Arguments: + The vault to remove, index or name + +Options: + -f, --force Force remove, will not return error if there is no vault with the given index or name + -h, --help Print help + -V, --version Print version +``` + +To remove a vault you need to provide the index or the name of the vault. If you +provide the index, the vault will be removed by its index, if you provide the +name, the vault will be removed the first vault with the given name. + +If there is no vault with the given index or name, an error will be returned, +unless you provide the `--force` option, in which case the command will not +return an error if there is no vault with the given index or name. + +## Examples +Remove a vault by its index: +```sh +lprs remove 1 +``` + +Remove a vault by its name: +```sh +lprs remove my-vault +``` + +Force remove a vault by its index: +```sh +lprs remove 234 --force +``` + +## Notes +- The index is one-based (the first vault is 1). diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..9313e44 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,13 @@ +# Installation + +Lprs can be installed using the pre-built binaries or by building from source +via `cargo-install` or `cargo build`, by default the lprs will check for +updates, if you don't want this behavior, you can disable it by passing the +`--no-default-features` flag to the `cargo-install` or `cargo build` command. +And for pre-built binaries, you will find a binary without `lprs-update-notify`, +this binary will not check for updates. + +- [Pre-built binaries](https://git.4rs.nl/awiteb/lprs/releases/latest) +- Install using `cargo-install`: `cargo install lprs` +- Building from source, clone the repository and run `cargo build --release` and + copy the binary from the `target/release` directory. \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..a238f24 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,58 @@ +# Lprs Documentation + +Welcome to the Lprs documentation. This documentation is intended to help you +get started with the Lprs command line tool `lprs`, and to provide you with a +reference for the various commands and options that are available. + +Lprs is a vault manager that allows you to store and retrieve secrets from a +vault. It is designed to be simple to use, and to provide a secure way to manage +your secrets. + +Lprs is not for human use only, it is also designed to be used in scripts as +well. + +## Encryption +In Lprs, we use the AES-256 CBC encryption algorithm to encrypt and decrypt the +vaults, we ask you for master password, which is used to encrypt and decrypt the +vaults, the master password will be hashed using SHA-256 and the hash will be +used as the key for the AES-256 CBC encryption algorithm. Also we don't store +the master password anywhere (even the hash of it), so if you forget it you will +lose all your vaults. + +## Storage +The vaults are stored in the program's directory, in a directory called `lprs` +and the file called `vaults.lprs`. + +### File location +The file location is dependent on the operating system you are using, here are +the locations for the different operating systems: + +| OS | Location | +|--------|-----------------------------------------------| +| Linux | `$HOME/.local/share/lprs/vaults.lprs` | +| MacOS | `$HOME/Library/Application Support/lprs/vaults.lprs` | +| Windows| `{FOLDERID_LocalAppData}\lprs\vaults.lprs` | + + +### File format +The list of vaults is stored in encrypted binary format. + +## Features +- Auto checks for updates (Can be disabled). +- Passing the master password as an argument and via stdin. +- Changing the master password. +- Generating a passwords. +- Store username, password, service name and notes in a vault. +- Custom fields, you can store any key-value pair in a vault. +- TOTP (Time-based One-Time Password) generation. Which can be used to generate + 2FA codes. +- Searching for vaults. And list all vaults in json format. +- Importing and exporting encrypted vaults (in json format). +- Importing and exporting from/to Bitwarden json format. (Unencrypted) +- Editing vaults. (The secrets can be passed as arguments or via stdin) +- Deleting vaults. +- Getting single field from a vault. (Useful for scripts) +- Ability to edit, get and remove a vault using its index or name. +- Auto completion for bash, elvish, fish, powershell and zsh +- Ability to import and export vaults with different master passwords. (Useful + for sharing vaults with others) \ No newline at end of file