diff --git a/.gitignore b/.gitignore index ea8c4bf..11e2b4a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /target +/book diff --git a/README.md b/README.md index b3c331f..b167742 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,89 @@ + +
+ # Lprs +A local vault manager designed to securely store and manage your vaults. -Lprs is a local vault manager designed to securely store and manage your vaults. +[![Docs](https://img.shields.io/badge/docs-lprs.4rs.nl-purple)](https://lprs.4rs.nl) +[![Crates.io](https://img.shields.io/crates/v/lprs?color=orange)](https://crates.io/crates/lprs) +[![Forgejo CI Status](https://git.4rs.nl/awiteb/lprs/badges/workflows/ci.yml/badge.svg)](https://git.4rs.nl/awiteb/lprs) +[![Forgejo CD Status](https://git.4rs.nl/awiteb/lprs/badges/workflows/cd.yml/badge.svg)](https://git.4rs.nl/awiteb/lprs) -### MSRV -The Minimum Supported Rust Version (MSRV) is `1.70.0`. +
+ +## 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) ## Installation -To install Lprs, you will need to have the Cargo package manager installed. If you do not have Cargo installed, you can install it by following the instructions [here](https://doc.rust-lang.org/cargo/getting-started/installation.html). - - -1. Install using [cargo-install](https://doc.rust-lang.org/cargo/commands/cargo-install.html): +### Build from source (MSRV: ) ```bash -cargo install lprs --locked -``` -This will enable the update notifications for Lprs. If you don't want to enable update notifications, you can install Lprs using: -```bash -cargo install lprs --locked --no-default-features +# From crates.io +cargo install lprs +# From source (after cloning the repository) +# The binary will be in target/release/lprs +cargo build --release ``` -2. Run Lprs: -```bash -lprs --help -``` +This will build Lprs with update checking enabled. If you want to disable update checking, you can build Lprs without the default features by passing the `--no-default-features` flag. -## Uninstallation -```bash -cargo uninstall lprs -``` +### Pre-built binaries +Pre-built binaries are available for Linux only, you can download them from the [releases page](https://git.4rs.nl/awiteb/lprs/releases/latest). ## Usage Lprs provides a command-line interface for managing your vaults. The following commands are available: ``` -A local CLI password manager +A local CLI vaults manager. For human and machine use Usage: lprs [OPTIONS] Commands: - add Add new vault - remove Remove vault - list List your vaults and search - clean Clean the vaults file - edit Edit the vault content - gen Generate a password - export Export the vaults - import Import vaults - help Print this message or the help of the given subcommand(s) + add Add new vault + remove Remove vault [alias `rm`] + list List your vaults and search [alias `ls`] + clean Clean the vaults file + edit Edit the vault content + gen Generate a password + get Get a entire vault or single field from it + export Export the vaults + import Import vaults + change-master-password Change the master password + completion Generate shell completion + help Print this message or the help of the given subcommand(s) Options: - -v, --vaults-file The vaults json file - -h, --help Print help - -V, --version Print version + -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 ``` -### Example -```bash -lprs add -n "Gmail" -u "some@gmail.com" -p $(lprs gen 19 -u -l -s) -s "https://mail.google.com" -``` - -#### Result -This is the result when search for it -``` -$ lprs list -e "mail" -p -s -Master Password: *************** -+-------+-------+----------------+---------------------+-------------------------+ -| Index | Name | Username | Password | Service | -+================================================================================+ -| 31 | Gmail | some@gmail.com | >NC`q$%+Nno 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..0eee9c1 --- /dev/null +++ b/docs/commands/change-master-password.md @@ -0,0 +1,32 @@ +# Changing the master password + +## Usage + +``` +Usage: lprs change-master-password [NEW_PASSWORD] + +Arguments: + [NEW_PASSWORD] The new master password, if there is no value for it you will prompt it + +Options: + -h, --help Print help +``` + +A command to change the master password of the vaults file, you can provide the +new password as an argument or you will be prompted for it. + +### Example +Prompt for the new master password +```bash +lprs change-master-password +``` + +Change the master password to `new-password` +```bash +lprs change-master-password 'new-password' +``` + +## Note +- The master password is used to encrypt and decrypt the vaults file, so if you + forget it you will lose all your vaults. +- This action is irreversible, so make sure to remember the new password. \ No newline at end of file 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